RenderBoy allows you to import and export design files from or to ordinary text files. Why would you want to do this? Well, it is an easy way for two people to exchange a design via email. Just export the design, then email it to a friend. They can import the file once they receive it. Other people may want to create a an import file programmatically from their own software. If neither of these capabilities sounds like something you need, feel free to skip this chapter. The main purpose of this chapter is to explain how to interpret/create the exported text files.
Icky Technical Details
One of my design goals with RenderBoy was to make it as non technical and WYSIWYG as I could. But, I'm afraid it's time to learn one or two of the inner workings of RenderBoy. To understand this chapter, you have no choice.
First, a cartesian (or X,Y,Z) coordinate system. Yup, RenderBoy has one, and it is used to position and orient all of the objects in your design. If you don't understand coordinate systems, then you will need to dig up a geometry text book, since I won't try to explain that here. Remember this picture from the "Design View Manipulation" chapter? It shows how the front, side, and top views are arranged in 3D space.
 
Well, suprise! This is really the X,Y,Z coordinate system! The X axis is the one coming out of the front view. The Y axis is the one coming out of the side view, and the Z axis is the one coming out of the top view. Or, if you prefer to think of it in terms of what you see on the screen:
 
Viewed here, the X-Y-Z coordinate system is arranged as follows:
Front View: X is out of the screen, Y is right, and Z is up.
Side View: X is left, Y is out of the screen, and Z is up.
Top View: X is down, Y is right, and Z is out of the screen.
Well, that's enough about coordinate systems. The next thing to understand is color. To specify a color, you need to numerically specify the fraction of red, green, and blue which make up the color. Red, green, and blue are the primary colors of light which combine to make up all the other colors. To understand this, I recommend you play with the standard color dialog box which you use to change the color of objects in RenderBoy. It will show you the red, green, and blue components of any color you select. Apple decided to show each color in a range from zero to 65,535, since that is how it is stored internally. I let you specify a color as a fraction in the range 0.0 to 1.0, which I think is simpler to use.
Import/Export Limitations
RenderBoy has one main limitation when it comes to importing and exporting files: It cannot import or export any textures which have been applied to a surface. If you do export a design file with a texture, RenderBoy will export the name of the texture only. Then when you import, you will be prompted to manually locate that texture file using the standard file dialog.
How does it work?
When RenderBoy is reading an import file, it just reads it like a book from top to bottom, and does what it says, line by line. Each line starts with a key word, followed by one or more words or parameters. Together, they tell RenderBoy what to do. Note that all of these words and parameters are case sensitive and must be typed exactly. For example, if the key word is supposed to be "OBJECT", then the key words "Object", "object", or "OBJECTS" just won't cut it. The computer is picky.
Also note that any time "the coordinate system" is mentioned, it refers to the X,Y,Z coordinate system as defined in the first part of this chapter.
Specifying Object Position
The CENTER keyword is used to specify the center of the next object(s) to be created. It is followed by three numbers, separated by spaces, and these are the X,Y,Z center of object(s) within the coordinate system. For example, the following specifies that the next object(s) created should be centered at X=10, y=20, and z=30:
CENTER 10 20 30
If no CENTER is specified, then the center is at (X,Y,Z) = (0,0,0)
Specifying Object Orientation
The ORIENTATION keyword is used to specify the orientation of the next object(s) to be created. It is followed by three numbers, separated by spaces, and these are the amount of rotation about the X axis, then the Y axis, then the Z axis of the coordinate system. For example, the following specifies that the next object(s) created should be rotated 10 degrees about the X axis and 20 degrees about the Y axis, and 30 degrees about the Z axis.
ORIENTATION 10 20 30
If no ORIENTATION is specified, then all three orientation angles are zero.
Specifying Object Dimensions
The DIMENSION keyword is used to specify the dimension(s) of the next object(s) to be created. It is followed by one to three numbers, separated by spaces, and these are interpreted differently, depending on the object(s) which get created. For objects which are defined by one dimension (like light surces), one parameter is interpreted as the outer diameter. For objects which are defined by two dimensions (like spheres), the two parameters are interpreted as the inner and outer diameters. For objects which are defined by three dimensions, the three parameters are either the length, inner diameter, and outer diameter (like for tubes, cones, and bells) or the length, width, and height (like for blocks, rods, and eggs). For example, the following specifies that any subsequent two dimension object (sphere) created should have an inner diameter of 20 and an outer diameter of 30.
DIMENSION 20 30
Specifying Object Color and Background Color
The COLOR keyword is used to specify the color of the next object(s) to be created. It is followed by three numbers, separated by spaces, and these are the fraction of red, green, and blue in the color of the next object(s) to be created. For example, the following specifies that the next object(s) created should be yellow, which is equal amounts of red and green, with no blue.
COLOR 1.0 1.0 0.0
If no COLOR is specified, then all three color values are 1.0 which results in a white object.
The BACKGROUND color keyword works in a similar way, except that it sets the background color of the eye view window and subsequent renderings. For example, to set the background color for subsequent renderings to blue, you could use:
BACKGROUND 0.0 0.0 1.0
Specifying Object Surface Properties
Keywords are available to specify the diffusion, reflectance, refraction, and shinyness of regular objects, as well as the intensity of light sources. All of these keywords are followed by one parameter, which is a fraction value from 0.0 to 1.0. For example, the following keywords specify that the next objects(s) created should be 20% diffuse, 30% reflective, and 50% refractive. Also note that these three values should always add to 100%.
DIFFUSION 0.2
REFLECTION 0.3
REFRACTION 0.5
The following keyword specifies that the next object(s) created should have a shinyness of 95%.
SHINIYNESS 0.95
The following keyword specifies that the next object(s) (specifically light sources) created should have an a brightness intensity of 80%.
INTENSITY 0.8
Specifying Object Clipping
The CLIPPING keyword is used to specify the clipping of the next object(s) to be created. It is followed by three words, separated by spaces, and these are the clipping status in the front view(x-axis), side view (y-axis), and top view (z-axis), respectively. The allowed words are NONE for no clipping, FAR to clip the far half of the object in that view, or NEAR to clip the near half of the object in that view. For example, the following specifies the next object(s) created should be clipped in the near half of the front view, the far half of the side view, and none of the top view:
CLIPPING NEAR FAR NONE
If no CLIPPING is specified, then no clipping is the default.
Specifying Object Creation
The OBJECT keyword is used to create an object, and it will be created with the location, dimension, etc which were most recently specified. The word OBJECT is followed by the type of object to create: SPHERE, EGG, ROD, TUBE, CONE, BELL, BLOCK, TRIANGLE, PYRAMID, or LIGHT. For the objects which are oriented along an axis (ROD, TUBE, CONE, and BELL) the object type must be followed by the keyword FRONT, SIDE, or TOP. Each object must also have the keyword POSITIVE or NEGATIVE appended to specify whether the object is positive or negative.
Here are some examples of valid OBJECT statements to create three objects: a positive sphere, a positive tube oriented with the side view, and a negative block:
OBJECT SPHERE POSITIVE
OBJECT TUBE SIDE POSITIVE
OBJECT BLOCK NEGATIVE
Specifying Eye View Settings
The EYE_VIEW keyword is used to specify the scale factor, rotation angle, height angle, and eye distance of the eye view. These are the same parameters controlled in the "Eye View Settings" dialog box. For example, the following would set the scale factor to 1.0, the rotation angle to 30 degrees, the height angle to 20 degrees, and the eye distance to one thousand:
EYE_VIEW 1.0 30 20 1000
You can also specify the coordinates of the eye view target location with the EYE_TARGET keyword. This is the point that the eye view is looking at. For example, to set the eye view target to (x,y,z) = (10,20,30), you would use:
